feat(gallery): reveal external generations that opt in with gallery:reveal - #9879

Summary

Stacked on #9876, which makes the gallery refresh when another client (e.g. a chatbot using the REST API) completes a generation for the signed-in user. This PR lets such a client ask for its result to be shown.

An external client opts in by enqueuing with destination: "gallery:reveal" (POST /api/v1/queue/default/enqueue_batch). When such an item completes for the signed-in user (any user in single-user mode), with a non-web-UI origin and not as a workflow-call child, a visible tab selects the board of the item's last saved (non-intermediate) image and then the image, through the same path as Find in Gallery. Preview follows the selection and the grid scrolls to it; a polite live-region message announces it once. destination: "gallery" stays refresh-only, because the legacy UI sends it for its own workflow and upscale runs.

The reveal never takes the Gallery from the user. It stands down when the user is typing (window focused and an editable field focused), the active project has an open run in this tab, a text or semantic search is active, more than one item is selected, a Find in Gallery or image-map selection is in flight, or the Gallery navigation changed since the completion arrived. These are checked again immediately before the first Gallery change. The newest completion wins. A hidden tab defers the newest request and re-evaluates everything when shown.

Image-map cluster selections now hold a gallery locator request while resolving, so nothing can supersede them mid-flight.

The contract for external clients is documented in features/gallery/README.md ("Realtime refresh and external reveal").

Related Issues / Discussions

Stacked on #9876.

QA Instructions

• pnpm check:release (in invokeai/frontend/webv2): passes. Run on Node 24.18.0 (.nvmrc pins 22.14.0). Two browser tests were flaky in earlier runs and passed on rerun: ConceptRow.browser.test.tsx (also flaky on unmodified main) and GalleryImageGrid.browser.test.tsx (failed once while files were being edited; passed 3/3 in isolation and in the final full run).
• Manual, multi-user server, UI open as user A. From a script logged in as A, enqueue a blank_image graph (is_intermediate: false, optional board) with origin: "external:test":
  • with destination: "gallery:reveal": the image's board and the image are selected, including after browsing to another board, and with focus left in a prompt field while the script runs in another window;
  • with the Invoke tab hidden, then shown: the reveal happens on showing;
  • without the destination: refresh only, selection unchanged;
  • with an active gallery search or a multi-selection: no reveal.

Review

Resolved: the opt-in originally reused "gallery", which the legacy UI also sends, so it now has its own value. The reveal could override user navigation or cancel an in-flight Find in Gallery; it now captures the navigation state on arrival, never supersedes, and checks again right before mutating. Active searches and multi-selections were overwritten; the reveal now stands down for both. Bursts could reveal an older item; newest-wins is now enforced. The result read fetched more than needed and now stops at the first saved image. Failures were silent and are now logged. The announcement was sticky and is now one-shot. Hidden tabs dropped reveals and now defer them. An over-strict typing check is fixed. A cluster-selection race is closed.

Known limitations, documented in the README:

• The status event carries no parent_item_id, so a workflow-call child completion supersedes an in-flight reveal before it is identified as a child.
• An image passed through from a graph's inputs can be picked if it is the last saved output.
• Every visible tab or device of the user may reveal.

Checklist

• The PR has a short but descriptive title, suitable for a changelog
• Meaningful regression coverage added / updated where needed; obsolete tests/code removed
• Persisted-state and API changes include required migrations / compatibility validation
• Relevant performance/efficiency opportunities considered; material claims have evidence
• Material review findings resolved and relevant checks rerun
• Documentation added / updated (if applicable)
• Updated What's New copy (if doing a release after this PR)

🤖 Generated with Claude Code

^{Need help on this PR? Tag @codesmith-bot with what you need.}